Tool Registration Arguments

The arguments to Tool.register are passed as a Lua table.

Example: Registration of a tool named MyTool

local _MyTool = Tool.register{
  name="MyTool",
  category="Analysis",
  regions=true,
  hasOverlays=true,
  parameters={
    {name="SomeInteger", type="int"}
  },
  results={
    {name="SomeValue", type="float"},
    {name="Pass", type="bool"}
  },
  thresholds={
    {"SomeValue", type="floatrange", range={0, 1000}, default={10,990}}
  }
}

These are the outermost settings in the arguments table:

name (string)
The name of the tool.
Default: The name of the app

This is an identifier, and should not contain spaces. The name displayed in the UI should be specified in Language resource files. The exact value of name is used if no translation is available.

category (string) required
The tool category, must be "Analysis".

subcategory (string)
The tool subcategory. Determines in which category the tool appears in the tool menu. Allowed values are "Classify", "CountAndFind", "Locate", "Measure", "Read", "Shape", "Verify", and "Other".
Default: "Other"

dimension (string)
Can be "2D" or "3D". This only affects which section in the tool menu the tool appears in for products that include both 2D and 3D tools. Set to "3D" if the tool uses the Height component (see input:getProviderData and Nova.Types.DataComponent) or if the tool performs a calculation in 3D space.

regions (boolean or regions definition)
Defines if the tool supports regions, and if so which types. Setting this to true will allow an unlimited number of 2D regions of any shapes. When true, or with a regions definition that is not limited to one region of a fixed type, the tool will have a UI control for specifying regions to operate on.
Default: false

hasOverlays (boolean)
When true, the tool can produce visualization overlays in the Nova viewer.
Default: false

Note

When using regions=true, it is usually best to set hasOverlays to true.

maxInstances (int)
The maximum number of simultaneous instances the tool allows. When not specified, the number of instances is unrestricted.
Default: unlimited

supportChildTools (boolean)
When true, tools can be inserted under this tool, and will be executed after. See Child tool functionality.
Default: false

requiresTeach (boolean)
This argument is used when a tool should have a teach process. When true, the tool requires a reference image. A teach panel is automatically displayed when a tool requires teach. It will only be possible to edit regions when Nova is in reference image view.
Default: false

parameters (parameter list)
A list of parameter definitions which define the set of configurable parameters for instances of a tool.
Default: none

results (result list)
A list of result definitions which define the set of result types the tool provides.
Default: none

thresholds (threshold list)
A list of threshold definitions which define the configurable pass/fail thresholds for the defined results.
Default: none

Regions definition

The supported regions for a tool can be defined by a table entry in Tool.register. The table can include the following settings:

is3D (boolean)
When true the tool will have 3D regions with a configurable height range.

maxNumber (int)
The maximum number of regions for the tool. Setting this to 1 means that the tool only supports one positive region.

shapes (table)
A list of one or more allowed region shapes.

The supported shapes for 2D tool regions are “RECTANGLE”, “ELLIPSE” and “POLYLINE”. For 3D tool regions only “RECTANGLE” and “ELLIPSE” are supported.

The example below shows the definition for a tool that can only have one 2D region with a rectangle or ellipse shape:

regions={is3D=false, maxNumber=1, shapes={"RECTANGLE", "ELLIPSE"}},

Parameter list

The parameters entry of the tool registration arguments is a list of parameter definitions. These define the user-configurable parameters of a tool.

parameters={
  {<parameter definition 1>},
  {<parameter definition 2>},
  {...}}
},

Parameter definition

parameters={
  {name="SomeInteger", type="int"}
}

A parameter is defined by a parameter definition table entry in the parameter list for Tool.register. The parameter values for these parameters are made available to tool instances via the parameters interface.

For the different types of parameters, see Parameter types.

General parameter definition fields

These fields can be used for most parameter types.

name (string) required
Specifies the name of the parameter.

This is an identifier, and should not contain spaces. The name displayed in the UI should be specified in Language resource files. The exact value of name is used if no translation is available.

type (string) required
Specifies the parameter type, see Parameter types.

default (type specific) type specific
Specifies the default value. The data-type depends on the type entry for the parameter, see Parameter types for specifics.

range (type specific) type specific
Specifies the possible range of values. The data-type depends on the type entry for the parameter, see Parameter types for specifics.

ui (boolean|table) type specific
Allows customizing the parameter appearance in the tool panel in the user interface.

When set to a boolean, this controls if the parameter is visible in the UI. With ui=false there will be no control for the parameter in the user interface.

When specified as a table, ui={...} some aspects of the UI representation can be controlled. The options are type-specific, see the documentation for the individual parameter types

affectsTeach (boolean)
When a tool requires teach, see requiresTeach in Tool Registration Arguments, it might be necessary for the tool to reteach after a parameter has been changed. In that case this property should be used to indicate that. If the reference image is removed, a parameter with this property set will be disabled since reteach is no longer possible.

optional (table)
When present, the parameter will be optional and can be enabled or disabled in the user interface. This value should be a table with a default-entry that specifies whether the optional parameter will be disabled (for default=false) or enabled (for default=true) initially. See Optional parameters for details.

Optional parameters

Optional parameters can be disabled with a checkbox in the user interface, and should, when disabled, not affect the tool.

A parameter is specified to be optional with the optional field:

    {name="MyOptional", optional={default=false}, type="intrange", range={0, 20}}

The default parameter to optional decides if the parameter is enabled by default (true) or disabled (false) when the tool is first created.

For optional parameters, “.value” must be specified explicitly to access the value:

  local myOptional = self.parameters.MyOptional.value

The enable-state is accessed with “.enabled”:

  local optionalEnabled = self.parameters.MyOptional.enabled

Result list

The results entry of the tool registration arguments is a list of result definitions. These define the results that a tool produces when executed.

results={
  {<result definition 1>},
  {<result definition 2>},
  {...},
}

Result definition

results={
  {name="SomeValue", type="int"}
}

A tool result is defined by a result definition table entry in the results list for Tool.register.

For the different types of results, see Result types.

Tools set the values for their defined results for an execution in their execute method using the output:add method.

A result definition can have a corresponding threshold definition that defines a customizable interval for determining the pass/fail-status of a result.

General result fields

These fields can be used for most result types.

name(string) required
Specifies the name of the result. If the result has a threshold, the threshold name should be the same as the result name.

type(string) required
Specifies the result type, see Result types.

Threshold list

The thresholds entry of the tool registration arguments is a list of threshold definitions. These should correspond to items in the result list, and define customizable ranges for determining the pass/fail result of the tool.

thresholds={
  {<threshold definition 1>},
  {<threshold definition 2>},
  {...},
}

Threshold definition

thresholds={
  {name="SomeValue", type="intrange", range={0, 1000}, default={10, 990}}
}

A threshold is defined by a threshold definition table entry in the threshold list entry to Tool.register. The name of a threshold should be the same as the name of a result definition.

A threshold definition defines a customizable interval that allows a user to specify the acceptable values of a result, within boundaries specified by the threshold.

Tools access the user-configured threshold values via self.thresholds in their execute method.

For the different types of thresholds, see Threshold types.

General threshold fields

These fields can be used for all thresholds. For the additional required fields that are type-dependent see Threshold types.

name(string) required
Specifies the name of the threshold. The name should be the same as the name of the result this threshold applies to.

type(string) required
Specifies the threshold type, see Threshold types.